<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>AngelScript: Garbage collection</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="test/javascript" src="touch.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('doc_gc.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Garbage collection </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Though AngelScript uses reference counting for memory management, there is still need for a garbage collector to take care of the few cases where circular referencing between objects prevents the reference counter from reaching zero. By default AngelScript automatically runs a few incremental steps of the garbage collector every time a new garbage collected object is created, this allows the destruction of garbage in an automatic way, yet doesn't waste time or disrupts the responsiveness of the application.</p>
<p>The automatic execution may not always be enough to clean up the garbage, for example, if the scripts create a lot of garbage with circular references. In this case the application may need to manually invoke the garbage collector from time to time. For this reason it is recommended that the application monitor the statistics for the garbage collector and adjust the frequency of the manual calls as necessary. The statistics is obtained through a call to <a class="el" href="classas_i_script_engine.html#a166e6cdd0cb35bcfd942824d8e882783">GetGCStatistics</a>, which returns the number of objects currently known to the garbage collector as well as the number of objects that have been destroyed and the number of object that have been detected as garbage with circular references.</p>
<p>The garbage collector implemented in AngelScript is incremental, so it can be executed for short periods of time without requiring the entire application to halt. For this reason, it is recommended that one or more calls to <a class="el" href="classas_i_script_engine.html#a17511a1de72ecdb836b974768f2ec422">GarbageCollect</a>(<a class="el" href="angelscript_8h.html#ac06582350753eb4d89d6ba9442eadf9da33a4cea43ee17e4f01bef742762e5af8">asGC_ONE_STEP</a>) is made at least once during the normal event processing. The number of calls that should be made depends on how much garbage is created.</p>
<p>If the scripts produce a lot of garbage but only a low number of garbage with circular references, the application can make a call to <a class="el" href="classas_i_script_engine.html#a17511a1de72ecdb836b974768f2ec422">GarbageCollect</a>(<a class="el" href="angelscript_8h.html#ac06582350753eb4d89d6ba9442eadf9da31e476bfb875b0f4fb209a3ef2540709">asGC_FULL_CYCLE</a> | <a class="el" href="angelscript_8h.html#ac06582350753eb4d89d6ba9442eadf9da61ab8361ad09823a287572d026efe7f1">asGC_DESTROY_GARBAGE</a>), which will only destroy the known garbage without trying to detect circular references. This call is relatively fast as the garbage collector only has to make a trivial local check to determine if an object is garbage without circular references.</p>
<p>Finally, if the application goes into a state where responsiveness is not so critical, it might be a good idea to do a full cycle on the garbage collector, thus cleaning up all garbage at once. To do this, call <a class="el" href="classas_i_script_engine.html#a17511a1de72ecdb836b974768f2ec422">GarbageCollect</a>(<a class="el" href="angelscript_8h.html#ac06582350753eb4d89d6ba9442eadf9da31e476bfb875b0f4fb209a3ef2540709">asGC_FULL_CYCLE</a>).</p>
<p>Should the automatic garbage collections not be desired, e.g. in critical inner loops where maximum performance is needed, it can easily be turned off with a call to <a class="el" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a>(<a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa9b5d1d8ff5143a6a77dfd18143d87c7d">asEP_AUTO_GARBAGE_COLLECT</a>, false).</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="doc_memory.html">Memory management</a></dd></dl>
<h1><a class="anchor" id="doc_gc_threads"></a>
Garbage collection and multi-threading</h1>
<p>The garbage collector itself is thread safe, but in order to be able to safely use the garbage collector in a multi-threaded environment the application must make sure all the objects that may be in the garbage collector has thread safe implementations of <a class="el" href="doc_gc_object.html">the GC behaviours</a>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="doc_gc_object.html#doc_reg_gcref_4">Garbage collected objects and multi-threading</a> </dd></dl>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun Dec 18 2016 12:35:28 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.3.1 </li>
  </ul>
</div>
</body>
</html>
